Inside Macintosh: QuickDraw GX Printing Extensions and Drivers /

Chapter 3 - Printer Drivers / Writing Printer Driver Files

The Message Overrides

The code that makes up your printer driver is a set of functions that override, either partially or totally, some of the printing messages that QuickDraw GX sends during the process of printing a document. This section describes how you use printing messages to develop your driver. It also describes how to use the printing collections to access and modify printing information, and how to use the nrequire macro to handle exceptions in your code.

Whenever you override a QuickDraw GX printing message, you must be certain that the declaration of your override function matches the declaration of the message. This means that the type of function return and the type of each parameter must match the types in the message declaration. The chapter "Printing Messages" shows the declaration of each printing messages.

QuickDraw GX provides a default implementation of each printing message that it sends. You can augment (partially override) some messages, and you can replace (totally override) others. For each printing message, QuickDraw GX provides one of three kinds of default implementations, as shown in Table 2-3 on page 2-12 in the chapter "Printing Extensions."

The contents of the file newapp.c, which contains the source code for the QuickDraw GX message overrides in the ImageWriter II printer driver, are shown in the QuickDraw GX sample code.

Choosing the Messages to Override

Which printing messages you need to override in your printer driver depends entirely on the characteristics of your device. Although QuickDraw GX provides default implementations of most messages (which means that you are not required to override them), there are some messages that you must override for raster or vector printing devices. Some drivers override many messages to provide their operations, and other drivers are created by overriding only a few messages.

Note

The action of the default implementation of each printing message is noted in the chapter "Printing Messages." Some of the default implementations provided by QuickDraw GX are empty (all that the function does is return).

Your message overrides for a different printing device are likely to be quite different than those for the ImageWriter II, which are shown in Table 3-2 on page 3-13. For example, the driver for the LaserWriter IIg creates a PostScript file during the printing process. This driver only needs to override a few messages to perform its tasks, as shown in Table 3-3.

Table 3-3 Message overrides for the LaserWriter IIg printer driver

Message	Why you override
GXPostScriptDoPageSetup	To add a PostScript setup string at the start of data for each page
GXOpenConnection	To create a file for the PostScript data
GXCloseConnection	To close the PostScript data file
GXInitialize	To allocate the message globals
GXDumpBuffer	To write the printer data to the file

The messages that your printer driver needs to override depend on the unique characteristics of your printing device. There is no set formula: what you have to do is familiarize yourself with the messages that are available from the printing system and look at the code for sample printer drivers. You can review the code for the sample drivers in the QuickDraw GX sample code, and you can examine the printing messages in the chapter "Printing Messages" in this book.

Forwarding Messages

Your printer driver can forward a message in its implementation of a partial override. If you are totally overriding a message, you do not forward it to other message handlers. You can forward the message either before or after performing your own actions. To forward a message to the next message handler in the message chain, use a statement with the following format:

anErr = Forward_MessageName(arguments);

For example, the ImageWriter II printer driver overrides the GXRasterLineFeed message to test whether it is printing in low resolution. If so, the override function, SD_LineFeed, temporarily alters the value of one of the parameters, forwards the message, and then resets the parameter value. Listing 3-3 shows the override of the GXRasterLineFeed message from the ImageWriter II printer driver.

Listing 3-3 Overriding the GXRasterLineFeed message

OSErr SD_LineFeed (Int16 *lineFeedSize, Ptr buffer,
                   UInt32 *bufferPos,
                   gxRasterImageDataHdl hImageData )
{
   OSErr    anErr;
   Boolean  amLowRes;
   short    actualLineFeed = *lineFeedSize;

   amLowRes = ((**hImageData).vImageRes == ff(72));
/* 
   If the user is printing in low-resolution mode, double the
   line-feed size because the ImageWriter line-feed commands are
   all expressed at 144 dpi.
*/
   if (amLowRes)
            *lineFeedSize <<= 1;
/*
   To get rid of the "paper dance" for blank color passes,
   optimize the small motions into groups.
*/
   {
   SpecGlobalsHdl    hGlobals= GetMessageHandlerInstanceContext();
   SpecGlobalsPtr    pGlobals= *hGlobals;

   if ( (pGlobals->packagingOptions == kDoSmallLineFeeds) ||
         (*lineFeedSize < -1) ||
         (*lineFeedSize >  1) )
      {
      *lineFeedSize += pGlobals->lineFeeds;
      pGlobals->lineFeeds = 0;
      /* do the line feed in the default way */
      anErr = Forward_GXRasterLineFeed(lineFeedSize, buffer,
                                    bufferPos, hImageData);
      }
   else
      {
      pGlobals->lineFeeds += *lineFeedSize;
      *lineFeedSize = 0;
      anErr = noErr;
      }
   }

   if (amLowRes)
      *lineFeedSize >>= 1;
   return(anErr);
} 

The SD_LineFeed override function tests the printing resolution. If the user is printing at low resolution (72 dots per inch), then the line-feed value is temporarily doubled to accommodate the fact that all line feeds are expressed in units of 144 dots per inch on the ImageWriter II. This function then forwards the GXRasterLineFeed message to allow the default implementation to send the appropriate character sequences. The GXRasterLineFeed message is described on page 4-98 in the chapter "Printing Messages."

Sending Messages

Your printer driver can also send a printing message to other message handlers. When you send a message, QuickDraw GX receives it and then sends it to the first message handler in the chain. To send a message, use a statement with this format:

anErr = Send_GXMessageName(arguments);

For example, to send the GXFreeBuffer message, use the following statement:

anErr = Send_GXFreeBuffer(bufferPtr); 

Handling Exceptions in Your Message Overrides

The code samples presented in this chapter make use of an exception-handling strategy that simplifies the job of testing for error conditions after each function call. This strategy uses three C macros to branch to error handlers in response to conditions. The error-handling macros are described in the section "Handling Exceptions in Your Message Overrides" beginning on page 2-14 in the chapter "Printing Extensions."

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help